MKDocs – 拡張プラグイン集(1)

MKDocs – 拡張プラグイン集(1)

#MkDocs
くにきち

くにきち

facebook logohatena logotwitter logo
Clock Icon2021.01.19

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

おひさしぶりです。しがないOLくにきちです。久々のブログ投稿になりました。 最近はドキュメント整備を主な仕事にしてまして（たまにリファクタリングやテスト）新しくドキュメント環境作ってみたりドキュメント書いたりして過ごしてます。

その中で、これまでドキュメント作成に使用していた GitBook CLI の開発が止まってしまったため、新しいドキュメント生成ツールを導入しよう！ということになりました。 導入の条件は色々ありましたが、今回導入に至ったのは「MKDocs」です。 簡単で、プラグインの豊富さやモダンな見ため、既存のドキュメントよりも見やすくなったのが決め手でした。

MkDocs の導入については、すでに弊社しんや (shinyaa31) による導入手順ブログ「プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ」があります。 導入手順はそちらをご覧ください。私もお世話になりました。

本ブログでは、MKDocs の拡張プラグインについて書いていきます。 上記導入手順でも拡張プラグインについていくつか書いており重複するものもありますが、自分の備忘録としてこちらにまとめて書いておきます。 ※ １ページですべてまとめたかったのですが、量が多くなってしまったのでページをわけます。

本ブログ内の手順における前提

次の設定でドキュメントを生成します。

  • Python Version: 3.8.5
  • mkdocs Version: 1.1.2
  • mkdocs-material Version: 6.2.5 (このテーマを使用します)

事前準備として次の手順を完了してください。

ドキュメントの構造

mkdocs-test\
    |_ docs\
        |_ index.md
        |_ test-plugin.md
    |_ mkdocs.yml

拡張プラグイン集

ここでは、MKDocs の拡張プラグインから私が有用だと感じたものを紹介します。 (MKDocs で使用できるすべてのプラグインを書いているわけではありません) ここで紹介する拡張プラグインは、mkdocs-material のみ対応しているものもありますので、「本ブログ内の手順における前提」でも書いたとおり、mkdocs-material テーマを使用して試してください。

ファビコン変更

ファビコンを任意の画像に変更できます。 今回はこの画像を使用します。

状態 イメージ
デフォルト
設定後

設定方法

  1. 画像用ディレクトリ (images) を作成し、ファビコンとして表示したい画像を格納します。 
    # 画像追加時のドキュメント構造
mkdocs-test/
    |_ docs/
        |_ index.md
        |_ test-plugin.md
        |_ images/
           |_ image1.png
    |_ mkdocs.yml

  2. 設定ファイルに画像のパスを指定します。 このとき、docs または docs_dir で指定したディレクトリを起点にパスを記述します。

    theme:
  # ファビコンの設定
  favicon: images/image1.png

アイコン変更

ファビコンと同様にドキュメントのヘッダーで表示するアイコンを任意の画像に変更できます。 ここではファビコンで使用したものと同じ画像を使用しますので、画像を格納する手順は割愛します。

状態 イメージ
デフォルト
設定後

設定方法

設定ファイルに画像のパスを指定します。 このとき、docs または docs_dir で指定したディレクトリを起点にパスを記述します。

theme:
    # アイコンの設定
    logo: images/image1.png

日本語検索の設定

material は、サイトの設定言語に基づいて検索言語を自動的に設定します。 設定ファイルの言語設定で language: ja と記述していれば日本語検索が可能です。

設定方法

theme:
    # サイトの言語設定
    language: ja

検索インデックスの単語区切り文字設定

設定ファイルで検索インデックス作成時の単語区切り文字をカスタマイズできます。 単語区切り文字をカスタマイズすることで、空白とハイフン (-) 以外の文字で区切られた単語にインデックスを付与できます。 デフォルト(未設定時)の単語区切り文字は、[\s\-]+ (空白とハイフン)です。

状態 イメージ
デフォルト
設定後

設定後のイメージは、デフォルトの空白とハイフン (-)に単語区切り文字としてドット (.) を追加した例です。 ドット (.) で区切られた単語 hoge にインデックスがついています。

設定方法

デフォルトの空白とハイフン (-)に単語区切り文字としてドット (.) を追加する場合、separator: '[\s\-\.]+' と記述します。

plugins:
    - search:
        # 検索インデックスの単語区切り文字設定
        separator: '[\s\-\.]+'

さらに単語区切り文字を追加したい場合は、[] 内に \ で区切って単語区切りに使用する文字を追加していきます。たとえば、ドット (.) に加え、さらにアンダースコア (_) を追加したい場合は [\s\-\.\_]+ のように指定します。

コードハイライト (Markdown 拡張)

codehilite を使用してコードブロックの構文を強調表示します。 コードハイライトには次のようなオプションを用意しています。

  • use_pygments: Pygmentsを使用してコードブロックを表示する設定 (Default: true) ※使用する場合は記述不要
  • noclasses: インラインスタイル (HTMLタグに直接スタイルを付与する方法)の設定 (Default: false)
  • pygments_style: Pygments スタイルの設定 (Default: default テーマ)
  • linenums: コードブロックの行番号表示 (Default: false)
状態 イメージ
デフォルト
設定後

設定後のイメージは、noclasses, pygments_style: colorful, linenums を指定した場合の例です。

設定方法

  1. 設定ファイルにコードハイライトの設定を記述します。 
    markdown_extensions:
    # コードハイライトの設定
    - codehilite:
        noclasses: true
        pygments_style: colorful
        linenums: true

  2. markdown には次のように記述します。

    ```java #ブロック内の言語を指定
public class HelloWorld {
    public static void main(String[] args){
        System.out.println("Hello World!!");
    }
}
```

PlantUML 表示設定 (Markdown 拡張)

PlantUMLを表示するための Markdown 拡張設定です。

状態 イメージ
デフォルト
設定後

設定方法

  1. plantuml-markdown をインストールします。 
    pip install plantuml-markdown

  2. PlantUML を描画するために「 plantuml-server 」の Docker イメージをダウンロードします。 (コマンドを実行するには Docker のインストールが必要です) 
    docker pull plantuml/plantuml-server

  3. 設定ファイルに PlantUML の設定を記述します。

    markdown_extensions:
    # PlantUMLの表示設定
    - plantuml_markdown:
        server: http://www.plantuml.com/plantuml

アラート修飾 (Markdown 拡張)

注意や警告を目立たせるために装飾する設定です。 インフォメーションや警告、ヒントなどをアイコンやカラーを使用して目立つように装飾します。 アラート修飾内では文字だけではなく、テーブルやリスト、コードブロックを表示できます。アラート装飾内にさらにアラート装飾を設定することも可能です。 ただし、デフォルトではアラート修飾内のネストされたブロックを考慮しないため、複数行のコードブロックを 1 行で表示してしまいます。 複数行のコードブロックを正しく表示するには、アラート修飾内にネストを考慮する設定(スーパーフェンス機能)を追加します。

※ コードブロックは、必要に応じて前述のコードハイライト設定をしてください。

設定方法

  1. 設定ファイルにアラート修飾の設定を記述します。 アラートの内容にコードブロックを埋め込まない場合は、スーパーフェンス機能を設定しなくて大丈夫です。

    markdown_extensions:
    # アラート修飾の設定
    - admonition
    # スーパーフェンス機能の設定
    - pymdownx.superfences

  2. markdown には !!! {ラベル名} で記述します。 独自のタイトルを付けたい場合は !!! {ラベル名} "{タイトル}" とし、タイトルを削除する場合は !!! {ラベル名} " " と記述します。 アラートの内容は、スペース 4 つでインデントしてから始めてください。

    !!! note
    これはノートです。
    
    * aaa
    * bbb

    | aaa
    | :---
    | hoge
    
    ```java
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("Hello World!!");
        }
    }
    ```

装飾の種類

アラート装飾は指定するラベルによってアイコンやカラーが変わります。 指定できるラベルと装飾のイメージは次のとおりです。

ラベル名 イメージ
note, seealso
abstract, summary, tldr
info, todo
tip, hint, important
success, check, done
question, help, faq
warning, caution, attention
failure, fail, missing
danger, error
bug
example
quote, cite

コンテンツの折りたたみ (Markdown 拡張)

コンテンツを折りたたんだ状態で表示します。アラート修飾と同様の表現ができます。 ドキュメント内をすっきりさせたい場合に便利です。

設定方法

  1. 設定ファイルにコンテンツの折りたたみ設定を記述します。 
    markdown_extensions:
    # コンテンツの折りたたみ設定
    - pymdownx.details
  2. markdown には次のように ??? {ラベル名} で記述します。内容は、アラート装飾と同様にスペース 4 つでインデントしてから始めてください。 読み込み時に折りたたみコンテンツを開いた状態で表示する場合は、???+ {ラベル名} と記述してください。 これらを組み合わせてネストしたコンテンツも作成できます。

    ??? note
    これはノートです。

    ??? note "ネストされた詳細 1"
        このように詳細のネストが可能です。
    ???+ note "ネストされた詳細 2"
        このように詳細のネストが可能です。

まとめ

今回紹介した設定や拡張プラグインを記述した設定ファイルと Markdown (test-plugin.md) はこのような感じです。 これらを適切に表示するにはライブラリのインストールなど別途操作を必要とするものがあり、この内容をコピーするだけではエラーになります。 各プラグイン紹介の「設定方法」を確認してください。

site_name: ドキュメントテスト
theme:
    name: material
    # サイトの言語設定
    language: ja
    # ファビコンの設定
    favicon: images/image1.png
    # アイコンの設定
    logo: images/image1.png
plugins:
    - search:
        # 検索インデックスの単語区切り文字設定
        separator: '[\s\-\.]+'
markdown_extensions:
    # コードハイライトの設定
    - codehilite:
        noclasses: true
        pygments_style: colorful
        linenums: true
    # PlantUMLの表示設定
    - plantuml_markdown:
        server: http://www.plantuml.com/plantuml
    # アラート修飾の設定
    - admonition
    # スーパーフェンス機能の設定
    - pymdownx.superfences
    # コンテンツの折りたたみ
    - pymdownx.details

# プラグインのテスト

## 検索テスト

検索のテストです。

| param    | name               | type
| :------- | :----------------- | :-----
| path     | `{customer_code}`  | string
| body     | `.customer_name`   | string
| body     | `.hoge[].hoge1`    | string

## コードハイライトのテスト

``` java
public class HelloWorld{
    public static void main(String[] args){
        System.out.println("Hello World!!");
    }
}
```

## PlantUMLのテスト

```plantuml
Bob->Alice : hello
```

## アラート装飾のテスト

!!! note
    これはノートです。
    
    * aaa
    * bbb

    | aaa
    | :---
    | hoge
    
    ```java
    public class HelloWorld{
        public static void main(String[] args){
            System.out.println("Hello World!!");
        }
    }
    ```

!!! note
    `note`, `seealso` ラベルで使用できる装飾です。

!!! abstract
    `abstract`, `summary`, `tldr` ラベルで使用できる装飾です。

!!! info
    `info`, `todo` ラベルで使用できる装飾です。

!!! tip
    `tip`, `hint`, `important` ラベルで使用できる装飾です。

!!! success
    `success`, `check`, `done` ラベルで使用できる装飾です。

!!! question
    `question`, `help`, `faq` ラベルで使用できる装飾です。

!!! warning
    `warning`, `caution`, `attention` ラベルで使用できる装飾です。

!!! failure
    `failure`, `fail`, `missing` ラベルで使用できる装飾です。

!!! danger
    `danger`, `error` ラベルで使用できる装飾です。

!!! bug
    `bug` ラベルで使用できる装飾です。

!!! example
    `example` ラベルで使用できる装飾です。

!!! quote
    `quote`, `cite` ラベルで使用できる装飾です。

## コンテンツの折りたたみテスト

??? note
    これはノートです。

    ??? note "ネストされた詳細 1"
        このように詳細のネストが可能です。
    ???+ note "ネストされた詳細 2"
        このように詳細のネストが可能です。

おわりに

今回は MKocs の拡張プラグインをいくつか紹介しました。 特に Markdown 拡張プラグインを使うと、きれいでスッキリとした見やすいドキュメントを作成できるので大変助かってます。 少し長くなってしまったので今回はここまでにして、次回この続きを書きたいと思います。 次は「Web アイコンフォント」や「タブ付きコンテンツ」などを紹介します。

ではまた。

Share this article

facebook logohatena logotwitter logo

関連記事

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

User avatar
川原征大
2024.10.10
Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

User avatar
たかやま
2023.10.30
Material for MkDocsのタイトルテキストをリンクテキストにする

Material for MkDocsのタイトルテキストをリンクテキストにする

User avatar
たかやま
2023.10.24
ドキュメントの文法(シンタックス)【CCG執筆者向け】

ドキュメントの文法(シンタックス)【CCG執筆者向け】

User avatar
川原征大
2023.09.11
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.